home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Libris Britannia 4
/
science library(b).zip
/
science library(b)
/
ELECTRON
/
H479.ZIP
/
PCRESON.ZIP
/
RESON.DOC
< prev
next >
Wrap
Text File
|
1992-02-05
|
69KB
|
1,968 lines
PC-RESON version 1.00
Command and Element Reference
February 1992
By John A. Priller and John Vincent
Edited by Becky Palmer-Scott
National Superconducting Cyclotron Laboratory
Michigan State University
East Lansing, MI 48824-1321
TABLE OF CONTENTS
COPYRIGHT INFORMATION & PROGRAM DESCRIPTION..................... 1
REQUIRED SOFTWARE & HARDWARE ................................... 2
RUNNING RESON .................................................. 3
CONVENTIONS & TIPS ON USING RESON FOR AC ANALYSIS .............. 4
Nomenclature: Elements, Terminals, and Nodes ................. 4
Circuit Nodes ................................................ 4
Voltage Loops ................................................ 4
Linear AC Analysis ........................................... 5
Current Flow ................................................. 5
Output Dimensions ............................................ 5
Tips ......................................................... 5
INPUT FILE FORMAT .............................................. 6
Text Format .................................................. 6
Upper and lower case ....................................... 6
Numeric fields ............................................. 6
Text strings ............................................... 7
Line Format .................................................. 7
Comment format ............................................. 7
Command format ............................................. 7
Element statement format ................................... 7
Sample Input Files ........................................... 8
OUTPUT FUNCTIONS ............................................... 9
V -- Voltage ................................................. 9
VD -- Device Voltage ......................................... 9
I -- Current ................................................ 10
ID -- Device Current ........................................ 10
IS -- Source Current ........................................ 10
IN -- Node Current .......................................... 10
P -- Power .................................................. 11
U -- Energy ................................................. 11
Q -- Quality Factor ......................................... 11
N -- Node Number at Given Terminal .......................... 11
RESON COMMANDS ................................................ 12
Define Data Parameters ...................................... 12
.MAT ...................................................... 12
.UNIT ..................................................... 12
.VSCALE ................................................... 12
Invoke Circuit Analysis ..................................... 13
.AC ....................................................... 13
.REPORT ................................................... 13
.INCLUDE .................................................. 13
Specify Output Appearance................................... 14
.COLUMNS .................................................. 14
.MARGIN ................................................... 14
.PRECISION ................................................ 14
.TITLE .................................................... 14
Specify and Generate Output Topics .......................... 15
.PRINT ................................................... 15
.OUTPUT ................................................... 16
.COUPLE ................................................... 17
.SHUNT .................................................... 17
(Continued on next page)
TABLE OF CONTENTS
(cont.)
RESON ELEMENT STATEMENTS: GENERAL FORMAT ...................... 18
NAME ........................................................ 18
Terminal Connections ........................................ 18
Required Parameters ......................................... 18
Optional Parameters ......................................... 18
RESON ELEMENT STATEMENTS: INDIVIDUAL FORMATS .................. 19
Components .................................................. 19
C -- Capacitor ............................................ 19
K -- Coupled coil ......................................... 19
L -- Inductor ............................................. 19
R -- Resistor ............................................. 19
Transmission lines ........................................ 20
T -- General transmission line .......................... 20
TC -- Coaxial transmission line ......................... 20
TR -- Rectangular (plate) transmission line ............. 20
Voltage Sources ............................................. 22
V -- Independent voltage source ........................... 22
H -- Current-controlled voltage source .................... 22
E -- Voltage-controlled voltage source .................... 22
Current Sources ............................................. 23
I -- Independent current source ........................... 23
F -- Current-controlled voltage source .................... 23
G -- Voltage-controlled voltage source .................... 23
ERROR MESSAGES ................................................ 24
RESON Errors ................................................ 24
Compiler Errors ............................................. 25
DOS errors ............................................... 25
I/O errors ............................................... 27
Critical errors .......................................... 28
Fatal errors ............................................. 28
- 1 -
COPYRIGHT INFORMATION
The copyright ((c) 1991, 1992) on this software product is held by
John Vincent, John A. Priller, and Michigan State University. All
rights are reserved. The above individuals and institutions
reserve the right to limit distribution of this software, within
the bylaws of Michigan State University, and within the copyright
laws of the State of Michigan and of the United States of America.
The authors of this software have used their best efforts in
preparing it. These efforts include development, research and
testing of the theories and algorithms to determine their
correctness and effectiveness. The authors of this software and
Michigan State University make no warranty of any kind, expressed
or implied, with regard to this software or to its documentation.
The authors of this software and Michigan State University shall
not be liable in any event for incidental or consequential damages
in connection with, or rising out of, the furnishing, performance,
use or misuse of this software.
PROGRAM DESCRIPTION
RESON is a enhanced AC circuit-analysis program modeled loosely on
SPICE. "Enhanced" means that beyond solving for voltages and
currents, RESON computes circulating and dissipated energy, and
allows for material properties and geometry. RESON also has
additional output functions and formats.
All of RESON's input and output files are standard ASCII, and can
be created and read by most computer systems. Input files look
similar to SPICE input files. Input files contain statements and
comments which describe the circuit and the analysis to be
performed. (Since the program currently does AC analysis only,
SPICE-like statements for DC or transient analysis are not
included). Output files have quote-delimited strings and comma-
delimited numeric fields, so that they may be easily imported into
spreadsheet programs (such as Lotus 123, or Borland's Quattro).
All user I/O and data management is performed by routines written
by John Priller, while the computation and analysis engine was
written by John Vincent. Please direct questions pertaining to
RESON to the appropriate individual.
- 2 -
REQUIRED SOFTWARE
RESON is shipped with the following files:
RESON.EXE -- The RESON program
RESON.DOC -- This document
MATERIAL.RSN -- The materials data file
UNITS.RSN -- The units data file
README.DOC -- Last-minute notes and information
*.DAT-- Sample input files
RESON requires the MS-DOS or PC-DOS version 2.1 (or higher)
operating system to run. It may also be possible to run RESON from
a Microsoft Windows 3.0 or OS/2 "DOS window", though this has not
yet been verified.
REQUIRED HARDWARE
RESON requires the following minimum hardware setup:
- An IBM-compatible PC with an Intel 8088 or higher CPU; an 80386
or i486 is preferred.
- A math coprocessor chip, such as an 80387 (the i486 chip
includes a math coprocessor) is recommended but not necessary.
- 640K of RAM
- A hard disk is recommended but not necessary.
- 3 -
RUNNING RESON
RESON reads an input file (e.g. RFSTUFF.DAT) and creates an *.OUT
file (e.g. RFSTUFF.OUT) and any other output files requested
in the input file (e.g. RFSTUFF.0...RFSTUFF.n). If errors are
encountered, error log RFSTUFF.LOG is created instead of the
output files.
RESON files consist of command statements and element statements
(described in this manual), and any desired comment statements.
To run RESON, type
RESON filename.ext ; RESON accepts any filename
or
RESON filename ; ".DAT" is assumed if no extender is
given
or
RESON filename.ext > nul ; "nul" prevents program status from
RESON filename > nul appearing on screen during the
run.
With each new RESON run, new output files are created -- RESON
will not append data from a new run onto an old output file. Old
output files with identical names will be destroyed. However,
during the same run, data can be appended to an existing output
table -- see the .PRINT, .OUTPUT, .COUPLE, and .SHUNT commands in
the section, "Specify and Generate Output Topics."
- 4 -
CONVENTIONS AND TIPS ON USING RESON FOR AC ANALYSIS
Nomenclature: Elements, Terminals, and Nodes
In RESON, "elements" are components or power sources, which
have "terminals" connecting them to a circuit. "Nodes" are the
circuit locations the terminals connect to.
In most statements, you replace each terminal designator with
the number of its circuit node. Terminals are numbered left to
right, so in this resistor definition,
RSHUNT 15 4 100k
terminal 1 connects to node 15, and terminal 2 to node 4.
However, terminal numbers are used explicitly in some .OUTPUT
and .PRINT functions. For the resistor defined above, the
following commands request the same voltage sets:
.PRINT AC V(15) V(4) ; Voltages at terminal 1
and terminal 2 requested
= with corresponding nodes
.PRINT AC VD(RSHUNT,1) VD(RSHUNT,2) ; Voltages at terminal 1
and terminal 2 requested
with terminal numbers
Circuit Nodes
Node numbers are always positive integers. They do not have to
be used sequentially -- node numbers may be skipped if desired.
Node 0 is reserved for ground. The circuit must have
connections to this node.
Each node (including ground) must have at least two
connections. RESON will check the circuit for this requirement
before attempting to process it. Nodes do not require a DC path
to ground.
Voltage Loops
Loops of voltage are illegal. RESON does not currently check
for this condition, so the user must take care that it does not
occur.
- 5 -
Linear AC Analysis
RESON's AC analysis solves for the small-signal frequency
response. All non-linear elements are made linear about the
operating point by user input model parameters or by idealized
default parameters. For example, if the model parameters
specify a gain of ten, then the gain remains ten no matter what
the input level. An input of 1 would result in an output of 10,
an input of 10 results in 100, etc. The gain has become linear.
Current Direction
1) Positive current flows in the direction positive charges
would go.
2) Positive current flows into component terminals.
3) Positive current flows through sources from the positive to
the negative terminal.
Output Dimensions
All output dimensions are in meters, regardless of input units.
See also Tips below.
Tips
-- To get average power and energy values from the output
functions, enter all source values in RMS units. To get peak
power and energy values, enter all source values in peak
units.
-- In most RESON statements, you need to replace the terminal
number with the corresponding circuit node.
-- RESON sweeps the frequency of the source(s) to determine the
circuit's response. If your circuit has only one AC input,
you can set the AC input equal to 1 with a phase angle of 0;
the output at any node will then conveniently reflect the
transfer function.
-- If you have a single input source set to 1 volt or 1 amp,
you can scale the resulting computed energies for some new
source value 'V' or 'I' by multiplying all energies by V*V
or I*I. (Also see .VSCALE command.)
- 6 -
INPUT FILE FORMAT
The circuit that RESON will analyze is described by a netlist.
This is a group of statements, each of which identifies a circuit
element, its interconnecting nodes, and its properties. In
addition to the netlist, a RESON input file also contains commands
that direct the analyses to be performed and the output to be
created. An input file may also include comment lines, which
describe the circuit and analyses for future reference. All of
these are described individually below.
Text Format
Upper and lower case
With the exception of 'm' and 'M' metric suffixes for
numeric fields, RESON is not case-sensitive; that is,
RTOP = Rtop = rTop
Numeric fields
Numeric fields in RESON can be either integer, floating
point 'F' or floating point 'E' format:
Integer : 0 7 91 8M
'F' floating point : 17.1m 35.88k 1641.002
'E' floating point : 1E-8 4.02E+6
As shown above, metric suffixes are supported for all real-
number fields (everything except terminal and node numbers).
The suffixes RESON recognizes are:
a,A (atto) = 1.0E-15 k,K (kilo) = 1.0E+03
p,P (pico) = 1.0E-12 M (mega) = 1.0E+06
n,N (nano) = 1.0E-09 g,G (giga) = 1.0E+09
u,U (micro) = 1.0E-06 t,T (tera) = 1.0E+12
m (milli) = 1.0E-03
No spaces or other characters may occur between the final
character of the number and the suffix, and any characters
beyond the initial suffix character are ignored. All formats
below are acceptable for denoting 4 megahertz (or 4 meg of
anything):
4000000.0 * Straight 'F' floating point with no suffix
4.0E+6 * 'E' floating point
4.0M * 'F' floating point with 'M' (mega) suffix
4Mhz * Integer with 'M' suffix -- the 'hz' is ignored
Note also that for milli- and mega-, the uppercase and
lowercase letter 'm' is distinct.
- 7 -
Text strings
Text strings can be at most 64 characters; element names are
limited to 10 characters. Strings enclosed within quotes may
contain any characters. Those not within quotes:
- Cannot begin with a number - May include percent (%)
- Cannot contain spaces - May include ampersand (&)
- May include dollar sign ($) - May include underscore (_)
Examples: A_STRING
"This is another string"
'So is this'
Line Format
Input file syntax is free-format, with fields separated by one
or more blanks, tabs, commas or parentheses. Carriage returns
mark the end of each input line. Blank lines are ignored.
Each RESON element or command must be defined on a single line,
although a line continuation character, the vertical bar (|),
can be placed at the end of a line to denote that the following
line is a continuation of the previous one:
* This comment looks like |
a single line to RESON!
Comment format
Comments begin with an asterisk (*) or a semi-colon (;), and
are ignored during input file processing. Comments may occur
at the end of command and element lines.
Command format
RESON command lines begin a period, just as SPICE commands
do. In the following descriptions, items in angle brackets
(<>) are mandatory, those within square brackets ([]) are
optional, and options separated by vertical bars (|) mean
that one and only one of the set may be chosen. (Do not
include brackets in actual RESON statements.)
Example: .REPORT <AC | DC> <frequency> [TITLE=string]
In this .REPORT command, AC or DC must be chosen; the
frequency must be given; there needn't be a title string.
Element statement format
No characters precede the element statement. See the RESON
ELEMENT STATEMENT sections for details on statement format.
- 8 -
Sample Input Files
These files can be found on the RESON program disk.
QWAVE2.DAT
Notice that element statements beginning "ISRC," "T1" and
"TR1" are disabled by the comment * preceding them.
;
; A quarter-wave resonator
;
; This example is from "Engineering Electromagnetics" by
; William H. Hayt, Fourth edition. pp 474 - 477.
; TC1 is the line described by Hayt while the rest of the
; lines are equivalent to TC1 using the available RESON
; models. Only one line per run should be uncommented.
;
; RLC.DAT is the equivalent shunt circuit of this resonator
;
; coupling has been added
.MAT SILVER
.Columns 6
.UNIT Centimeter
*ISRC 1 0 53.2uA 0
V1 999 0 61.912mV 0.0
Cc 999 1 1.368pF
TC1 1 2 0 Ri=1 Ro=2.72 L=37.5 E=4 QE=1000
*T1 1 2 0 Z0=30.0 TD=2.5nS E=4 QE=1000 RABAC=4.026uOhms
RCOMAC=1.48uOhms
*TR1 1 2 0 Z0=30.0 Wa=6.2832 Wc=17.0903 L=37.5 E=4 QE=1000
*TR1 1 2 0 H=1.86 Wa=6.2832 Wc=17.0903 L=37.5 E=4 QE=1000
R1 1 0 100Mohm
VShort 2 0 0.0 0.0
.AC LIN 25 98.310Mhz 98.560Mhz
.PRINT AC V(1) I(VShort)
.Report AC 98.378940Mhz
.Output 1 "" ALL $ VDm(1) IDm(1) Pc Pe Ue Uh
*.Couple 1 "Test Capacitive Couple" Node=1 Z0=50
*.Couple 1 "Test Tline Couple" Tname=TC1 Z0=50
;
;
RLC.DAT
;
; A RLC equivalent shunt circuit model of QWAVE2.DAT
;
.Columns 6
V1 999 0 62.890mV 0.0
Cc 999 1 1.368pF
L1 1 0 60.74nH
C1 1 0 41.64pF
R1 1 0 26.56kOhms
.AC LIN 25 98.310Mhz 98.560Mhz
.PRINT AC V(1) I(VShort)
.Report AC 98.4700Mhz
.Output 1 "" ALL $ VDm(1) IDm(1) Pc Pe Ue Uh
- 9 -
OUTPUT FUNCTIONS
Output functions, used in the .OUTPUT and .PRINT commands, compute
or return results based on RESON analysis. They begin with an
identifier, such as "V" or "P," which specifies the type of
information desired, and which is sometimes followed by an
operator: "i," "r," "m," or "p" to describe a complex number
component or "c," "e," or "h" to describe the type of power or
energy. Most functions also list the circuit nodes, element names,
and/or terminals the information is about. Element names are
always omitted in .OUTPUT function statements.
This section describes the functions available. In the following
descriptions, items in angle brackets (<>) are mandatory, those
within square brackets ([]) are optional, and options separated by
vertical bars (|) mean that one and only one of the set may be
chosen. In addition, items in {} brackets must be in .PRINT
commands but should not be in .OUTPUT commands. Include
parentheses but not brackets in actual RESON statements.
V -- Voltage (volt):
Determines the potential difference between two nodes, where
V = V(nodeX) - V(nodeY).
V[i|r|m|p](nodeX[,nodeY])
i = imaginary part Example: VM(11) for .PRINT
r = real part
m = magnitude
p = phase
nodeX = a node number
nodeY = another node number; if not entered, node 0 is
assumed
VD -- Device Voltage (volt):
Determines the potential difference between the element
terminals or between an element terminal and ground, where
VD = VD(terminalX) - VD(terminalY).
VD[i|r|m|p]({element,}terminalX[,terminalY])
i = imaginary part Examples: VD(1,2) for .OUTPUT
r = real part VD(1) for .OUTPUT
m = magnitude VD(C16,1,2) for .PRINT
p = phase VD(C16,1) for .PRINT
element = element name
terminalX = a terminal number
terminalY = another terminal number; if not entered, the
potential difference between terminalX and
node 0 is assumed.
- 10 -
I -- Current (ampere):
Determines the current through a voltage source.
I[i|r|m|p](vname)
i = imaginary part Example: IM(V1) for .PRINT
r = real part
m = magnitude
p = phase
vname = voltage source name
ID -- Device Current (ampere):
Determines the current entering a device terminal.
ID[i|r|m|p]({element,}terminal)
i = imaginary part Examples: ID(1) for .OUTPUT
r = real part ID(C8,1) for .PRINT
m = magnitude
p = phase
element = element name
terminal = terminal #
IS -- Source Current (ampere):
Determines all current from current source(s) attached to the
node.
IS[i|r|m|p](node)
i = imaginary part Example: IS(11) for .PRINT
r = real part
m = magnitude
p = phase
node = node number
IN -- Node Current (ampere):
Determines the total current crossing a node. (Currently
doesn't work properly.)
IN[i|r|m|p](node)
i = imaginary part Example: IN(4) for .PRINT
r = real part
m = magnitude
p = phase
node = node number
- 11 -
P -- Power (watt):
Determines the energy dissipated due to conduction currents,
electric energy, magnetic energy, or the energy delivered by
any source. Power delivered is negative; power dissipated is
positive. If no subscript modifier is given, the total power
(Pc + Pe + Ph) is reported.
P[c|e|h]{(element)}
c = conductive losses Examples: P for .OUTPUT
e = electric P(R17) for .PRINT
h = magnetic PH(R44) for .PRINT
element = element name
U -- Energy (VAR):
Determines the magnetic or electric reactive energy. If no
subscript modifier is given, the total energy (Ue + Uh) is
reported.
U[e|h]{(element)}
e = electric Examples: U for .OUTPUT
h = magnetic Ue for .OUTPUT
element = element name Uh(LTOP) for .PRINT
Q -- Quality Factor:
Determines the quality factor Q, which equals energy/power;
(Q = U/P).
Q{(element)}
element = element name Examples: Q for .OUTPUT
Q(CAP1) for .PRINT
N -- Node Number at Given Terminal:
Determines the node number to which the specified terminal is
connected.
N({element,}terminal)
element = element name Examples: N(1) for .OUTPUT
terminal = terminal # N(CAP1,1) for .PRINT
- 12 -
RESON COMMANDS
In the following descriptions, items in angle brackets (<>) are
mandatory, those within square brackets ([]) are optional, and
options separated by vertical bars (|) mean that one and only one
of the set may be chosen. (Do not include brackets in actual RESON
statements.)
Define Data Parameters
The following commands provide default values for the input
file. See RESON ELEMENT STATEMENTS for individualized parameter
definitions.
.MAT <material>
Defines the material that RESON should use in calculating
default properties for subsequent elements. Supported
materials are listed in the MATERIAL.RSN data file, and the
first material in this file (usually COPPER) is the default
material if none is specified. Additional materials may be
added to the MATERIAL.RSN file by the user. Multiple .MAT
commands may be used to define parts of the circuit which
are made of differing materials.
Example: .MAT SILVER
.UNIT <unit_name>
Defines the units that RESON should use in size
specifications and in calculating default properties for
subsequent elements. Supported units are listed in the
UNITS.RSN file, and the first unit in this file (usually the
METER) is the default unit if none is specified. Additional
units may be added to the UNITS.RSN file by the user.
Multiple .UNIT commands can be used to define different
parts of the circuit.
Example: .UNIT INCH
.VSCALE <node> <value>
Scales the matrix solution so that the voltage at the given
node is the given value. Only one .VSCALE command is allowed
per case.
Example: .VSCALE 17 100
- 13 -
Invoke Circuit Analysis
.AC LIN <NumIntervals> <Start-Freq> <End-Freq>
Performs an AC analysis of the circuit defined by the input
file, over the region of frequencies specified. LIN
indicates a linear division of the frequency range.
Example: .AC LIN 10 8.9MHz 9.1MHz
.REPORT AC <frequency> [TITLE=string]
Performs a circuit analysis. Multiple .REPORT commands in an
input file will be processed in the order encountered.
Example: .REPORT AC 1.0MHz TITLE="Test circuit at 1Mhz"
.INCLUDE <filename>
Processes the specified input file for RESON commands and
elements. Any number of nested .INCLUDE files may be
specified (.INCLUDEd files may .INCLUDE other files).
Example: .INCLUDE "SUBCIRC.DAT"
- 14 -
Specify Output Appearance
.COLUMNS <number>
Specifies the maximum number of data columns for .PRINT,
.OUTPUT, .COUPLE, and .SHUNT commands. Default is 5. Only
one .COLUMNS command per input file will be obeyed; if more
than one is encountered, the last one will be used.
Example: .COLUMNS 8
.MARGIN <number>
Defines left margin of RESON output. Default is 6 spaces.
Example: .MARGIN 12
.PRECISION <freq-precision> <other-precision>
Specifies the number of significant digits to use in
floating-point output. "freq-precision" specifies the number
of significant digits for frequency output; "other-
precision" specifies the number of significant digits for
all other floating-point output. Only one .PRECISION
command per input file will be obeyed; the last one will be
used. The default for .PRECISION is 6, 4. The width of a
floating point data column is:
column width = 6 + significant digits + comma + space
= significant digits + 8
6 significant digits = +0.00000E+00 ; width = 14
4 significant digits = +0.000E+00 ; width = 12
Commas are added to the output to insure compatibility with
spreadsheet import formats.
Example: .PRECISION 8 6
.TITLE <string>
Specifies the title for the RESON case. "string" is a text
string and must be within quotes if more than one word.
Example: .TITLE "Test Resonator"
- 15 -
Specify and Generate Output Topics
.PRINT AC <function-list>
Writes data from the previous .AC analysis command to a
filename.OUT file. ("filename" is the same as the input
"filename".) Multiple .PRINT commands can exist in an input
file; the data will be appended to filename.OUT. Function
lists consist of one or more functions from the following
table:
Function Description Example
------------------------------------------------------------
P[c|e|h](element) ; Power P(R44)
U[e|h] ; Energy Ue(CAP1)
Q(element) ; Quality factor Q(CAP1)
N(element,terminal) ; Node # at terminal N(CAP1,1)
V[r|i|m|p](node1[,node2]) ; Voltage VM(11)
I[r|i|m|p](vname) ; Current IM(V1)
IN[r|i|m|p](node) ; Node current IN(4)
IS[r|i|m|p](node) ; Source current IS(11)
VD[r|i|m|p](element, ; Device voltage VD(C16,1,2)
terminalX[,terminalY])
ID[r|i|m|p](element, ; Device current ID(C8,1)
terminal)
------------------------------------------------------------
where and
P = Power c = conductive losses
U = Energy e = electrical energy
Q = Quality factor h = magnetic energy
N = Node # at given terminal r = real part
V = Voltage i = imaginary part
IN = Node current m = magnitude
IS = Source current p = phase
VD = Device voltage
ID = Device current
Examples: .PRINT AC V(15) V(4)
.PRINT AC VD(RSHUNT,1) VD(RSHUNT,2)
.PRINT AC ISR(11) VM(11) I(12) V(12)
- 16 -
.OUTPUT <output-file#> <title> <element-list> $ <function-list>
Generates a table from a previous .REPORT analysis, with
functions in the columns and elements in the rows. Multiple
.OUTPUT commands may exist for each .REPORT .
.OUTPUT command format is below. Note the required '$'
between the element list and function list. Also, the number
of functions requested must be less than the number of
columns requested by the .COLUMNS command.
output-file# :
The numeric extender of the output file: filename.0 to
filename.9. ("filename" is automatically the same as
the input "filename".) With each new RESON run, a brand
new output file is opened, if requested. If .OUTPUT
commands repeat the file extender during the RESON run,
the data will be appended to the output file.
title :
Text-string title for the output.
element-list :
The elements to include in the output rows. Elements
may be specified individually, in groups, or in a
combination of the two: Examples:
TR17 : Rectangular transmission line TR17
TR : All rectangular transmission lines
C : All capacitors
C1-R12: Input file elements from C1 to R12, in order
ALL : All elements in input file order
function-list :
The data to be displayed in the output columns.
Includes any of the following:
VD[i|r|m|p](tx[,ty]) : Device Voltage
ID[i|r|m|p](t) : Device Current
Q : "Q" quality factor
P[c|e|h] : Power (W) ; If no subscripts,
U[e|h] : Energy (VA) ; total is given.
where and
P = Power c = conductive losses
U = Energy e = electrical energy
Q = Quality factor h = magnetic energy
VD = Device voltage r = real part
ID = Device current i = imaginary part
m = magnitude
p = phase
Examples: .OUTPUT 1 "Parallel resonator Response" R L C $ Ue P
.OUTPUT 0 "" TR R1-C11 $ VD(1,2) ID(1)
- 17 -
.COUPLE <output-file#> <title> <node=# | Tname=xxx> <Z0=R>
Generates data from the last .REPORT analysis. Multiple
.COUPLE commands may exist for each analysis. Matches a feed
transmission line of characteristic impedance "Z0" to the
circuit. If "node=#" is requested, reports the series
capacitance and frequency shift needed at that node. If
"Tname" is requested, reports the distance from terminal t2
of "Tname" transmission line where the feed transmission
line can be tied directly. The result is valid only if the
circuit is resonant.
output-file# : The numeric extender of the output file:
filename.0 to filename.9. ("filename" is
automatically the same as the input "filename".) With
each new RESON run, a brand new output file is opened,
if requested. If .OUTPUT commands repeat the file
extender during the run, the data will be appended to
the output file.
title : Text-string title for the output.
node=# : The statement "node=#" where "#" is the node
number of the circuit to couple to.
Tname : The statement "Tname=xxx" where "xxx" is the name
of the transmission line to couple to.
Z0=R : The statement "Z0=R", where "R" is the
characteristic impedance (in ohms) of the feed line to
match to the circuit.
Examples: .COUPLE 1 "Capacitive Coupler" node=6 Z0=50
.COUPLE 0 "Direct Feed" Tname=T11 Z0=50
.SHUNT <output-file#> <title> <node#>
Generates data from the last .REPORT analysis. Multiple
.SHUNT commands may exist for each analysis. Determines the
equivalent shunt circuit at the specified circuit node. The
result is only valid if the circuit is resonant.
output-file# : The numeric extender of the output file:
filename.0 to filename.9. ("filename" is
automatically the same as the input "filename".) With
each new RESON run, a brand new output file is opened,
if requested. If .OUTPUT commands repeat the file
extender during the run, the data will be appended to
the output file.
title : Text-string title for the output.
node# : The node number at which to determine the
equivalent shunt circuit.
Example: .SHUNT 0 "Shunt circuit at node 10" 10
- 18 -
RESON ELEMENT STATEMENTS: GENERAL FORMAT
Element statements define the circuit that RESON will analyze.
Statement structures vary, but have several parts in common:
NAME <t1>..<tn> <required_parameter=#>..[optional_parameter=#]...
NAME
An element NAME can be up to 10 characters long. The first
character (and second character, in the case of transmission
lines) determines what type of element is being defined. The
rest of the name is determined by the user. Element names in a
circuit must be unique! First characters of names are:
C... : capacitor
K... : coupled coil
L... : inductor
R... : resistor
V... : independent voltage source
H... : current-controlled voltage source
E... : voltage-controlled voltage source
I... : independent current source
F... : current-control current source
G... : voltage-control current source
T... : general transmission line
TC... : coaxial transmission line
TR... : rectangular transmission line
Terminal Connections
t1..tn specify the terminal connections of the element. To
insert an element into a circuit, you simply replace each
terminal designator with the number of the circuit node it
connects to. Terminals are numbered left to right, so in this
resistor definition:
RSHUNT 15 4 100k
terminal 1 connects to node 15, and terminal 2 to node 4.
Required Parameters
Most required parameters will be a single number, but some take
the form of XX=value, where XX is a one-or-more character
identifier string, followed by an optional =, followed by a
value (almost always a number).
Optional Parameters
Optional parameters always have the XX=value form. They must
appear AFTER the required element parameters, but may appear in
any order among themselves.
- 19 -
RESON ELEMENT STATEMENTS: INDIVIDUAL FORMATS
Components
RESON follows the standard engineering convention that positive
current flows in the direction that positive charges would go,
and flows into component terminals.
C -- Capacitor:
C... <t1> <t2> <value> [Q=value]
Specifies a capacitor, with value specified in farads. If no
Q is specified, it is assumed to be infinite. Replace t1 and
t2 with the circuit nodes they connect to.
K -- Coupled coil:
K... <L1> <L2> <value>
Couples two inductors, L1 and L2. Value is the coupling
coefficient, and must be between 0 and 1. Establishes a
mutual inductance, M, between L1 and L2, where M =
value*SQRT(L1*L2).
L -- Inductor:
L... <t1> <t2> <value> [Q=value]
Specifies an inductor, with value given in henries. The
default Q value is infinite, if none is specified. Replace
t1 and t2 with the circuit nodes they connect to.
R -- Resistor:
R... <t1> <t2> <value>
Specifies a resistor. Value is in ohms. Replace t1 and t2
with the circuit nodes they connect to.
- 20 -
Transmission lines:
A transmission line consists of two conductors of equal
length. t1 and t2 are the terminal connections to the
primary conductor, while both ends of the return conductor
are tied to terminal t3. The voltage on the primary
conductor varies according to the "unsimplified" lossy
transmission line equations, while the voltage on the return
conductor is held constant to the node voltage where t3 is
tied. The current on the return conductor mirrors the
current on the primary conductor.
All length/width/height/radius parameters are assumed to be
given in the currently selected units defined by the .UNIT
command. All resistances are calculated using the default
material parameters defined by the .MAT command. Si, So, Sa
and Sc override these conductivity parameters.
All dimensions are output in meters, regardless of input.
General transmission line:
T... <t1> <t2> <t3> <Z0=value> <TD=value> <RABDC=value>
<RABAC=value> [RCOMDC=value] [RCOMAC=value] [E=value]
[M=value] [QE=value] [QM=value]
Coaxial transmission line:
TC... <t1> <t2> <t3> <Ri=value> <Ro=value> <L=value>
[Si=value] [So=value] [E=value] [M=value] [QE=value]
[QM=value]
Conductor resistance default values are computed from the
conductor materials defined by the .MAT command. Si= and
So= parameters will override these defaults.
Rectangular (plate) transmission line:
TR... <t1> <t2> <t3> <Wa=value> <Wc=value> <L=value>
[Z0=value | H=value] [Sa=value] [Sc=value] [E=value]
[M=value] [QE=value] [QM=value]
If height (H) is specified, Z0 is computed assuming the
width of each conductor is the average of Wa and Wc. If
Z0 is specified, Wa and Wc are simply used for power
calculations and height is irrelevant. At all times the
current density of the primary and return conductors is
assumed to be uniform.
See parameter definitions on next page.
- 21 -
t1 : Terminal 1; replace with corresponding circuit
node.
t2 : Terminal 2; replace with corresponding node.
t3 : Terminal 3; replace with corresponding node.
E=n : Relative permittivity of media between
conductors. Default = 1.0.
M=n : Relative permeability of media between
conductors. Default = 1.0.
QE=n : Electric material quality factor (1/loss_tangent)
computed from electric energy and losses (a
measure of fill material losses due to electric
fields). Default = infinity.
QM=n : Magnetic material quality factor (1/loss_tangent)
computed from magnetic energy and losses (a
measure of fill material losses due to magnetic
fields). Default = infinity.
Z0=n : Characteristic impedance in ohms.
Td=n : Time delay from t1 to t2, in seconds.
RABDC=n : DC resistance per meter of conductor spanning t1
to t2. Default = 0.0.
RABAC=n : AC resistance per meter per sqrt(Hz) of conductor
spanning t1 to t2. Default = 0.0.
RCOMDC=n : DC resistance per meter of return conductor.
Default = 0.0.
RCOMAC=n : AC resistance per meter per sqrt(Hz) of return
conductor. Default = 0.0
Ri=n : Radius of inner conductor in current units.
Ro=n : Radius of outer conductor in current units.
Sa=n : Conductivity of primary conductor (mhos/meter).
Sc=n : Conductivity of return conductor (mhos/meter).
Si=n : Conductivity of inner conductor (mhos/meter).
So=n : Conductivity of outer conductor (mhos/meter).
Wa=n : Width of primary conductor in current units.
Wc=n : Width of return conductor in current units.
L=n : Length of both conductors in current units.
H=n : Height between conductors in current units.
- 22 -
Voltage Sources
For sources, RESON presumes that current flows from t1
(positive terminal) to t2 (negative terminal).
Replace t1 and t2 with the circuit nodes they connect to.
V -- Independent voltage source:
V... <t1> <t2> <magnitude> <phase>
Specifies an independent voltage source, with positive
current flowing from terminals t1 to t2. Magnitude is
specified in volts, phase in degrees.
H -- Current-controlled voltage source:
H... <t1> <t2> <Vname> <transresistance>
Specifies a current-controlled voltage source between
terminals t1 and t2. Vname is any independent voltage source
defined elsewhere in the circuit. The voltage source has the
value of I(Vname)*transresistance.
E -- Voltage-controlled voltage source:
E... <t1> <t2> <NC1> <NC2> <gain>
Specifies a voltage-controlled voltage source between
terminals t1 and t2. NC1 and NC2 are the positive and
negative controlling nodes, respectively. The voltage source
has the value of (V(NC1)-V(NC2))*gain.
- 23 -
Current Sources
For sources, RESON presumes that current flows from positive
to negative nodes.
Replace t1 and t2 with the circuit nodes they connect to.
I -- Independent current source:
I... <t1> <t2> <magnitude> <phase>
Specifies an independent current source, where t1 and t2 are
the positive and negative terminals, respectively. Current
is assumed to flow from t1 through the source to t2.
Magnitude is specified in amps, phase in degrees.
F -- Current-controlled current source:
F... <t1> <t2> <Vname> <gain>
Specifies a current-controlled current source placed between
terminals t1 and t2. Vname is any independent voltage source
defined elsewhere in the circuit. The current source the
value of I(Vname)*gain.
G -- Voltage-controlled current source:
G... <t1> <t2> <NC1> <NC2> <transconductance>
Specifies a voltage-controlled current source placed between
terminals t1 and t2. NC1 and NC2 are the positive and
negative controlling nodes, respectively. The current source
has the value of (V(NC1)-V(NC2))*transconductance.
- 24 -
ERROR MESSAGES
There are two types of error codes encountered during RESON use:
1. those detected by the RESON program, and
2. compiler run-time errors detected by Turbo Pascal. This type
of error will have the format:
Run-time error nnn at xxxx:yyyy
All errors that don't look like that are RESON errors.
RESON Errors
Error # : Code Description
---------------------------------------------------------
0 : No errors encountered
1 : Matrix size is less than 1
2 : Matrix size cannot exceed CNarraysize (200)
3 : Matrix has not been opened
4 : No solution exists
5 : Source or element not found
6 : Problem not solved
7 : Index out of range
8 : User node not found
9 : Maximum number of elements or sources exceeded
10 : No elements or sources defined
11 : Illegal node connection(s)
12 : Element specifications not complete enough for
attempted operation
13 : Using default parameters
14 : Illegal element value(s)
15 : Problem nodes not defined
16 : Invalid terminal specifications
17 : Element name already exists
18 : No circuit owner, or circuit owner is nil
19 : Circuit not post-processed
20 : Unknown element type
21 : Not enough memory
--------------------------------------------------------
- 25 -
Compiler Errors
(The following was copied from Appendix A of the Turbo Pascal
Programmer's Guide, v.6.0.)
Run-time errors cause the program to terminate and display an
error message:
Run-time error nnn at xxxx:yyyy
where "nnn" is the error number and "xxxx:yyyy" is the error
address (segment and offset).
Run-time errors are divided into four categories: DOS errors 1
through 99; I/O errors, 100 through 149; critical errors, 150
through 199; and fatal errors, 200 through 207.
-----------------------------------------------------------
DOS errors
1 : Invalid function number
You made a call to a non-existent DOS function.
2 : File not found
Reported by Reset, Append, Rename, or Erase if the
name assigned to the file variable does not specify
an existing file.
3 : Path not found
-- Reported by Reset, Rewrite, Append, Rename, or
Erase if the name assigned to the file variable is
invalid or specified a nonexistent subdirectory.
-- Reported by ChDir, MkDir, or RmDir if the path is
invalid or specified a nonexistent subdirectory.
4 : Too many open files
Reported by Reset, Rewrite, or Append if the program
has too many open files. DOS never allows more than
15 open files per process. If you get this error with
less than 15 open files, it may indicate that the
CONFIG.SYS file does not include a FILES=xx entry or
that the entry specifies too few files. Increase the
number to some suitable value, for instance, 20.
- 26 -
5 : File access denied
-- Reported by Reset or Append if FileMode allows
writing and the name assigned to the file variable
specifies a directory or a read-only file.
-- Reported by Rewrite if the directory is full or if
the name assigned to the file variable specifies a
directory or an existing read-only file.
-- Reported by Rename if the name assigned to the
file variable specifies a directory or if the new
name specifies an existing file.
-- Reported by Erase if the name assigned to the file
variable specifies a directory or a read-only
file.
-- Reported by MkDir if a file with the same name
exists in the parent directory, if there is no
room in the parent directory, or if the path
specifies a device.
-- Reported by RmDir if the directory isn't empty, if
the path doesn't specify a directory, or if the
path specifies the root directory.
-- Reported by Read or BlockRead on a typed or
untyped file if the file is not open for reading.
-- Reported by Write or BlockWrite on a typed or
untyped file if the file is not open for writing.
6 : Invalid file handle
This error is reported if an invalid file handle is
passed to a DOS system call. It should never occur;
if it does, it is an indication that the file
variable is somehow trashed.
12 : Invalid file access code
Reported by Reset or Append on a typed or untyped
file if the value of FileMode is invalid.
15 : Invalid drive number
Reported by GetDir or ChDir if the drive number is
invalid.
16 : Cannot remove current directory
Reported by RmDir if the path specifies the current
directory.
17 : Cannot rename across drives
Reported by Rename if both names are not on the same
drive.
- 27 -
-----------------------------------------------------------
I/O errors
These errors cause termination if the particular statement
was compiled in the {$|+} state. in the ($|-} state, the
program continues to execute, and the error is reported by
the IOResult function.
100 : Disk read error
Reported by Read on a typed file if you attempt to
read past the end of the file.
101 : Disk write error
Reported by Close, Write, WriteIn, Flush, or Page
if the disk becomes full.
102 : File not assigned
Reported by Reset, ReWrite, Append, Rename, and
Erase if the file variable has not been assigned a
name through a call to Assign.
103 : File not open
Reported by Close, Read, Write, Seek, Eof, FilePos,
FileSize, Flush, BlockRead, or BlockWrite if the
file is not open.
104 : File not open for input
Reported by Read, ReadIn, Eof, Eoln, SeekEof, or
SeekEoln on a text file if the file is not open for
input.
105 : File not open for output
Reported by Write and WriteIn on a text file if the
file is not open for output.
106 : Invalid numeric format
Reported by Read or ReadIn if a numeric value read
from a text file does not conform to the proper
numeric format.
- 28 -
-----------------------------------------------------------
Critical errors
150 : Disk is write-protected
151 : Unknown unit
152 : Drive not ready
153 : Unknown command
154 : CRC error in data
155 : Bad drive request structure length
156 : Disk seek error
157 : Unknown media type
158 : Sector not found
159 : Printer out of paper
160 : Device write fault
161 : Device read fault
162 : Hardware failure
Refer to your DOS programmers' reference manual for more
information about critical errors.
-----------------------------------------------------------
Fatal errors
These errors always immediately terminate the program.
200 : Division by zero
The program attempted to divide a number by zero
during a 1, mod, or div operation.
201 : Range check error
This error is reported by statements compiled in
the {$R+} state when one of the following
situations arises:
-- The index expression of an array qualifier was
out of range.
-- You attempted to assign an out-of-range value to
a variable.
-- You attempted to assign an out-of-range value as
a parameter to a procedure or function.
202 : Stack overflow error
This error is reported on entry to a procedure or
function compiled in the {$S+} state when there is
not enough stack space to allocate the subprogram's
local variables. Increase the size of the stack by
using the $M compiler directive.
This error may also be caused by infinite
recursion, or by an assembly language procedure
that does not maintain the stack project.
- 29 -
203 : Heap overflow error
This error is reported by New or GetMem when there
is not enough free space in the heap to allocate a
block of the requested size.
204 : Invalid pointer operation
This error is reported by Dispose or FreeMem if the
pointer is nil or points to a location outside the
heap, or if the free list cannot be expanded due to
a full free list or to HeapPtr being too close to
the bottom of the free list.
205 : Floating point overflow
A floating-point operation produced a number too
large for Turbo Pascal or the numeric coprocessor
(if any) to handle.
206 : Floating point underflow
A floating-point operation produced an underflow.
This error is only reported if you are using the
8087 numeric coprocessor with a control word that
unmasks underflow exceptions. By default, an
underflow causes a result of zero to be returned.
207 : Invalid floating point operation
-- The real value passed to Trunc or Round could
not be converted to an integer within the
Longint range (-2,147,483,648 to 2,147,483,647).
-- The argument passed to the Sqrt function was
negative.
----------------end-of-author's-documentation---------------
Software Library Information:
This disk copy provided as a service of
Public (software) Library
We are not the authors of this program, nor are we associated
with the author in any way other than as a distributor of the
program in accordance with the author's terms of distribution.
Please direct shareware payments and specific questions about
this program to the author of the program, whose name appears
elsewhere in this documentation. If you have trouble getting
in touch with the author, we will do whatever we can to help
you with your questions. All programs have been tested and do
run. To report problems, please use the form that is in the
file PROBLEM.DOC on many of our disks or in other written for-
mat with screen printouts, if possible. PsL cannot debug pro-
programs over the telephone, though we can answer questions.
Disks in the PsL are updated monthly, so if you did not get
this disk directly from the PsL, you should be aware that the
files in this set may no longer be the current versions. Also,
if you got this disk from another vendor and are having prob-
lems, be aware that some files may have become corrupted or
lost by that vendor. Get a current, working disk from PsL.
For a copy of the latest monthly software library newsletter
and a list of the 4,000+ disks in the library, call or write
Public (software) Library
P.O.Box 35705 - F
Houston, TX 77235-5705
Orders only:
1-800-2424-PSL
MC/Visa/AmEx/Discover
Outside of U.S. or in Texas
or for general information,
Call 1-713-524-6394